---
title: 安裝 Astro
sidebar:
  label: 安裝
description: '如何安裝 Astro 並開始一個新專案'
i18nReady: true
---
import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';

[`create astro` CLI 指令](#從-cli-精靈安裝)是從零開始一個新 Astro 專案最快的方法。它會引導你完成設定新 Astro 專案的每個步驟，並讓你從幾個不同的官方起始模板中選擇。

你也可以加上 `template` 選項來執行 CLI 指令，以使用任何現有的主題或起始模板來開始你的專案。探索我們的[主題和起始模板展示](https://astro.build/themes/)，你可以在那裡瀏覽部落格、作品集、文件網站、登陸頁面等主題！

如果你想手動安裝 Astro，請參閱我們的[手動安裝指南](#手動安裝)。

:::tip[線上預覽]
想在瀏覽器中試用 Astro 嗎？前往 [astro.new](https://astro.new/) 瀏覽我們的起始模板，並在不離開瀏覽器的情況下建立新的 Astro 專案。
:::

## 環境要求

- **Node.js** - `v18.20.8` 或 `v20.3.0`、`v22.0.0` 或更高版本。（不支援 `v19` 和 `v21`。）
- **文字編輯器** - 我們推薦使用 [VS Code](https://code.visualstudio.com/) 搭配我們的[官方 Astro 擴充功能](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)。
- **終端機** - Astro 是透過命令列介面（CLI）來使用的。

## 瀏覽器相容性

Astro 是使用 Vite 建構的，預設支援具有現代 JavaScript 功能的瀏覽器。完整的參考資料，請參閱 [Vite 目前支援的瀏覽器版本清單](https://vite.dev/guide/build.html#browser-compatibility)。

## 從 CLI 精靈安裝

你可以在電腦的任何地方執行 `create astro`，所以在開始之前不需要為你的專案建立新的空目錄。如果你還沒有為新專案準備空目錄，CLI 精靈會自動幫你建立一個。

<Steps>
1. 在終端機中執行以下指令來啟動安裝精靈：

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      # 使用 npm 建立新專案
      npm create astro@latest
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      # 使用 pnpm 建立新專案
      pnpm create astro@latest
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      # 使用 yarn 建立新專案
      yarn create astro
      ```
      </Fragment>
    </PackageManagerTabs>

    如果一切順利，你會看到成功訊息，然後是一些建議的後續步驟。

2. 現在你的專案已經建立，你可以 `cd` 進入新的專案目錄來開始使用 Astro。

3. 如果你在 CLI 精靈過程中跳過了「Install dependencies?」的步驟，請務必在繼續之前安裝相依套件。

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm install
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn install
      ```
      </Fragment>
    </PackageManagerTabs>

4. 你現在可以[啟動 Astro 開發伺服器](/zh-tw/develop-and-build/#啟動-astro-開發伺服器)並在建構時看到專案的即時預覽！
</Steps>

## CLI 安裝選項

你可以在執行 `create astro` 指令時加上額外選項以自訂設定過程（例如對所有問題回答「是」、跳過 Houston 動畫）或你的新專案（例如是否安裝 git、新增整合）。

<ReadMore>查看[所有可用的 `create astro` 指令選項](https://github.com/withastro/astro/blob/main/packages/create-astro/README.md)。</ReadMore>

### 新增整合

你可以在啟動新 Astro 專案的同時，在 `create astro` 指令中傳遞 `--add` 參數來安裝任何[官方整合](/zh-tw/guides/integrations-guide/)或支援 `astro add` 指令的社群整合。

在你的終端機中執行以下指令，替換為任何支援 `astro add` 指令的整合：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 建立具有 React 和 Partytown 的新專案
  npm create astro@latest -- --add react --add partytown
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 建立具有 React 和 Partytown 的新專案
  pnpm create astro@latest --add react --add partytown
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 建立具有 React 和 Partytown 的新專案
  yarn create astro --add react --add partytown
  ```
  </Fragment>
</PackageManagerTabs>

### 使用主題或起始模板

使用 `create astro` 命令時，你可以加上 `--template` 參數來基於[官方範例](https://github.com/withastro/astro/tree/main/examples)或任何 GitHub 儲存庫的 `main` 分支建立新的 Astro 專案。

在你的終端機中執行以下指令，將官方的 Astro 模板名稱或你想使用的主題的 GitHub 使用者名稱和儲存庫名稱替換進去：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # 使用官方範例建立新專案
  npm create astro@latest -- --template <example-name>

  # 基於 GitHub 儲存庫的 main 分支建立新專案
  npm create astro@latest -- --template <github-username>/<github-repo>
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # 使用官方範例建立新專案
  pnpm create astro@latest --template <example-name>

  # 基於 GitHub 儲存庫的 main 分支建立新專案
  pnpm create astro@latest --template <github-username>/<github-repo>
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # 使用官方範例建立新專案
  yarn create astro --template <example-name>

  # 基於 GitHub 儲存庫的 main 分支建立新專案
  yarn create astro --template <github-username>/<github-repo>
  ```
  </Fragment>
</PackageManagerTabs>

預設情況下，此指令會使用模板儲存庫的 `main` 分支。若要使用不同的分支名稱，請將其作為 `--template` 參數的一部分傳遞：`<github-username>/<github-repo>#<branch>`。

## 手動安裝

本指南將帶你逐步手動安裝和設定新的 Astro 專案。

如果你不想使用我們的自動化 `create astro` CLI 工具，可以按照以下指南自行設定專案。

<Steps>
1. 建立你的目錄

    建立一個以你的專案名稱命名的空目錄，然後進入該目錄。

    ```bash
    mkdir my-astro-project
    cd my-astro-project
    ```

    進入新目錄後，建立專案的 `package.json` 檔案。這是你管理專案相依套件（包括 Astro）的方式。如果你不熟悉這個檔案格式，請執行以下指令來建立一個。

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm init --yes
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm init 
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn init --yes
      ```
      </Fragment>
    </PackageManagerTabs>

2. 安裝 Astro

    首先，在專案內安裝 Astro 專案相依套件。

    :::note[重要]
    Astro 必須在本地安裝，而非全域安裝。請確保你**沒有**執行 `npm install -g astro`、`pnpm add -g astro` 或 `yarn add global astro`。
    :::

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install astro
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm add astro
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn add astro
      ```
      </Fragment>
    </PackageManagerTabs>

    然後，將 `package.json` 中任何佔位符的 "scripts" 區段替換為以下內容：

    ```json title="package.json" del={3} ins={4-6}
    {
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "dev": "astro dev",
        "build": "astro build",
        "preview": "astro preview"
      },
    }
    ```

    你將在本指南後續步驟中使用這些腳本來啟動 Astro 並執行其不同的指令。

3. 建立你的第一個頁面

    在文字編輯器中，於目錄的 `src/pages/index.astro` 建立新檔案。這將是專案中你的第一個 Astro 頁面。

    在本指南中，複製並貼上以下程式碼片段（包括 `---` 虛線）到新檔案中：

    ```astro title="src/pages/index.astro"
    ---
    // 歡迎來到 Astro！三重虛線程式碼圍欄之間的所有內容
    // 都是你的「元件 frontmatter」。它永遠不會在瀏覽器中執行。
    console.log('這會在你的終端機中執行，而不是瀏覽器！');
    ---
    <!-- 以下是你的「元件模板」。它只是 HTML，但加入了
        一些魔法來幫助你建構出色的模板。 -->
    <html>
      <body>
        <h1>Hello, World!</h1>
      </body>
    </html>
    <style>
      h1 {
        color: orange;
      }
    </style>
    ```

4. 建立你的第一個靜態資源

    你也會想要建立 `public/` 目錄來存放靜態資源。Astro 總是會在最終建構中包含這些資源，所以你可以安全地從元件模板內部參照它們。

    在文字編輯器中，於 `public/robots.txt` 建立新檔案。`robots.txt` 是一個簡單的檔案，大多數網站都會包含它來告訴搜尋機器人（如 Google）如何處理你的網站。

    在本指南，複製並貼上以下程式碼片段到新檔案中：

    ```diff title="public/robots.txt"
    # 範例：允許所有機器人掃描和索引你的網站。
    # 完整語法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt
    User-agent: *
    Allow: /
    ```

5. 建立 `astro.config.mjs`

    Astro 是使用 `astro.config.mjs` 來設定的。如果你不需要設定 Astro，這個檔案是可選的，但你可能希望現在就建立它。

    在專案根目錄建立 `astro.config.mjs`，並將下面的程式碼複製到其中：

    ```js title="astro.config.mjs"
    import { defineConfig } from "astro/config";

    // https://astro.build/config
    export default defineConfig({});
    ```

    如果你想在專案中包含 [UI 框架元件](/zh-tw/guides/framework-components/)（如 React、Svelte 等）或使用其他工具（如 MDX 或 Partytown），這裡就是你要[手動匯入和設定整合](/zh-tw/guides/integrations-guide/)的地方。

    <ReadMore>閱讀 Astro 的 [API 設定參考](/zh-tw/reference/configuration-reference/)以獲取更多資訊。</ReadMore>

6. 新增 TypeScript 支援

    TypeScript 是使用 `tsconfig.json` 來設定的。即使你不撰寫 TypeScript 程式碼，這個檔案也很重要，這樣 Astro 和 VS Code 等工具才知道如何理解你的專案。沒有 `tsconfig.json` 檔案，編輯器不會完全支援某些功能（如 npm 套件匯入）。

    如果你確實打算撰寫 TypeScript 程式碼，建議使用 Astro 的 `strict` 或 `strictest` 模板。你可以在 [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/) 查看和比較三種模板設定。

    在專案根目錄建立 `tsconfig.json`，並將下面的程式碼複製到其中。（你可以使用 `base`、`strict` 或 `strictest` 做為 TypeScript 模板）：

    ```json title="tsconfig.json" "base"
    {
      "extends": "astro/tsconfigs/base"
    }
    ```

    <ReadMore>閱讀 Astro 的 [TypeScript 設定指南](/zh-tw/guides/typescript/#setup)以獲取更多資訊。</ReadMore>

7. 後續步驟

    如果你已按照上述步驟操作，你的專案目錄現在應該看起來像這樣：

    <FileTree>
    - node_modules/
    - public/
      - robots.txt
    - src/
      - pages/
        - index.astro
    - astro.config.mjs
    - package-lock.json 或 `yarn.lock`、`pnpm-lock.yaml` 等
    - package.json
    - tsconfig.json
    </FileTree>

8. 你現在可以[啟動 Astro 開發伺服器](/zh-tw/develop-and-build/#啟動-astro-開發伺服器)，並在建構時看到專案的即時預覽！

</Steps>
